 <!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <meta name="apple-mobile-web-app-capable" content="yes" />
        <meta name="apple-mobile-web-app-status-bar-style" content="black" />
        <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1.0, maximum-scale=1.0, minimal-ui" />
        
        <title>Form Element Documentation</title>
        
        <script src="/js/greyspots.js" type="text/javascript"></script>
        <link href="/css/greyspots.css" type="text/css" rel="stylesheet" />
        
        <script src="/js/ace/ace.js" data-ace-base="/js/ace/" type="text/javascript" charset="utf-8"></script>
        <script src="/js/ace/ext-language_tools.js" type="text/javascript"></script>
        <script src="/js/ace/ext-searchbox.js" type="text/javascript"></script>
        
        <script src="doc-library/doc.js" type="text/javascript"></script>
        <link href="doc-library/doc.css" type="text/css" rel="stylesheet" />
    </head>
    <body>
        <gs-jumbo>
            <h1 class="text-center">Form</h1>
        </gs-jumbo>
            
        <gs-container min-width="sml;med;lrg">
            <h3 class="doc-header">Tag:</h3>
            <div class="doc-section doc-mono">
                <pre>&lt;gs-form src="..."&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;template&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...
&nbsp;&nbsp;&nbsp;&nbsp;&lt;/template&gt;
&lt;/gs-form&gt;</pre>
            </div>
            
            <h3 class="doc-header">Description:</h3>
            <div class="doc-section">
                <p>The &lt;gs-form&gt; element is for selecting and updating records in the database. In most cases the form is used to select and update a single record but it can update multiple records.</p>
            </div>
            
            <h1 class="doc-header">Examples:</h1>
            <div class="doc-section">
                <div class="doc-example-description">
                    <span class="h3">Skeleton Example:</span>
                    <p>This is an example of a basic form. This form will have the following behaviours:</p>
                    <ol>
                        <li><p>) Each control will be filled with the value of it's column.</p></li>
                        <li><p>) When you change the value of a control and you press return or move focus: The record will be updated with the new value.</p></li>
                    </ol>
                </div>
                <gs-doc-example>
                    <template for="html" height="13">
                        <gs-form src="gsdoc.tpeople" where="id=2341">
                            <template>
                                <label for="first_name">First Name:</label>
                                <gs-text id="first_name" column="first_name"></gs-text>
                                
                                <label for="last_name">Last Name:</label>
                                <gs-text id="last_name" column="last_name"></gs-text>
                            </template>
                        </gs-form>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[suppress-no-record-found]</code>:</span>
                    <p>The <code>[suppress-no-record-found]</code> attribute prevents the form from erroring when there's is no record found.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="26">
                        <gs-form src="gsdoc.tpeople" suppress-no-record-found where="id = 123456789">
                            <template>
                                <label>First Name:</label>
                                
                                <gs-text column="first_name"></gs-text>
                                <label>Last Name:</label>
                                <gs-text column="last_name"></gs-text>
                            </template>
                        </gs-form>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[where]</code>:</span>
                    <p>The <code>[where]</code> attribute determines which record(s) we get from the database.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="26">
                        <gs-form src="gsdoc.tpeople" where="id = 2341">
                            <template>
                                <label>First Name:</label>
                                <gs-text column="first_name"></gs-text>
                                
                                <label>Last Name:</label>
                                <gs-text column="last_name"></gs-text>
                                <hr />
                            </template>
                        </gs-form>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[limit]</code>:</span>
                    <p>By setting the limit attribute we are allowing multiple records in the form. The limit attribute defaults to: "1".</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="26">
                        <gs-form src="gsdoc.tpeople" where="id > 2341" limit="2">
                            <template>
                                <label>First Name:</label>
                                <gs-text column="first_name"></gs-text>
                                
                                <label>Last Name:</label>
                                <gs-text column="last_name"></gs-text>
                                <hr />
                            </template>
                        </gs-form>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[offset]</code>:</span>
                    <p>By setting the offset attribute we are shifting the records we see.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="26">
                        <gs-form src="gsdoc.tpeople" where="id > 2341" limit="2" offset="2">
                            <template>
                                <label for="first_name">First Name:</label>
                                <gs-text id="first_name" column="first_name"></gs-text>
                                
                                <label for="last_name">Last Name:</label>
                                <gs-text id="last_name" column="last_name"></gs-text>
                                <hr />
                            </template>
                        </gs-form>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[ord]</code>:</span>
                    <p>The "ord" attribute sets the ORDER BY that we get the records using.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="26">
                        <gs-form src="gsdoc.tpeople" where="id > 2341" limit="2" ord="first_name ASC">
                            <template>
                                <label for="first_name">First Name:</label>
                                <gs-text id="first_name" column="first_name"></gs-text>
                                
                                <label for="last_name">Last Name:</label>
                                <gs-text id="last_name" column="last_name"></gs-text>
                                <hr />
                            </template>
                        </gs-form>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[lock]</code>:</span>
                    <p>The "lock" attribute changes what column the form uses to make sure the record it's updating hasn't been updated by someone else first. Default of this attribute is "change_stamp".</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="15">
                        <gs-form src="gsdoc.tpeople" where="id=2341" lock="change_stamp">
                            <template>
                                <label for="first_name">First Name:</label>
                                <gs-text id="first_name" column="first_name"></gs-text>
                                
                                <label for="last_name">Last Name:</label>
                                <gs-text id="last_name" column="last_name"></gs-text>
                            </template>
                        </gs-form>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[qs=""]</code>:</span><br />
                    <p>The name <code>[qs]</code> stands for "querystring". The querystring is the part in the URL after the "?". The <code>[qs]</code> attribute has two formats, each with their own use.</p>
                    
                    <ul>
                        <li>qs="<i>key1</i>=<i>attribute1</i>". This format allows you to fill any attribute with any key from the querystring. To use multiple keys from the querystring you can put a comma-separated list of these expressions (for example: qs="<i>key1</i>=<i>attribute1</i>,<i>key2</i>=<i>attribute2</i>"). If you need an attribute to be added when a querystring key is not present, replace the "=" with "!=" (for example: qs="<i>key1</i>!=<i>attribute1</i>", attribute1 will only be added if key1 is not in the querystring). As a shorthand, if the key in the querystring is the same name as the attribute you want to fill, you can omit the attribute name in the expression (for example: qs="<i>key1</i>="). If an expression doesn't find it's key in the querystring: it reverts the attribute that it fills to it's original value.</li>
                        <li>qs="<i>key</i>". This format will update the <code>[value]</code> attribute with the querystring whenever the querystring changes.</li>
                    </ul>
                </div>
                <gs-doc-example query-string="test1=2342&test2=2342">
                    <template for="html" height="35">
                        <gs-form src="gsdoc.tpeople" qs="test1">
                            <template>
                                <gs-text column="first_name"></gs-text>
                            </template>
                        </gs-form>
                        <br />
                        <gs-form src="gsdoc.tpeople" qs="test2=value">
                            <template>
                                <gs-text column="first_name"></gs-text>
                            </template>
                        </gs-form>
                        <br />
                        <gs-form src="gsdoc.tpeople" qs="test3=hidden">
                            <template>
                                <gs-text column="first_name"></gs-text>
                            </template>
                        </gs-form>
                        <br />
                        <gs-form src="gsdoc.tpeople" qs="test4!=hidden">
                            <template>
                                <gs-text column="first_name"></gs-text>
                            </template>
                        </gs-form>
                        <br />
                        <br />
                        <gs-grid widths="1,1">
                            <gs-block>
                                <gs-button onclick="GS.pushQueryString('test1=2341');">Add "test1"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.removeFromQueryString('test1');">Remove "test1"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.pushQueryString('test2=2341');">Add "test2"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.removeFromQueryString('test2');">Remove "test2"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.pushQueryString('test3=yes');">Add "test3"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.removeFromQueryString('test3');">Remove "test3"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.pushQueryString('test4=yes');">Add "test4"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.removeFromQueryString('test4');">Remove "test4"</gs-button>
                            </gs-block>
                        </gs-grid>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[refresh-on-querystring-values]</code>:</span>
                    <p>The "refresh-on-querystring-values" attribute refreshes the form element when any of the columns in the attribute change in the query string. To put multiple columns in the attribute you would just put in comma seperated list.</p>
                </div>
                <gs-doc-example query-string="id=2341&unrelatedparameter=test">
                    <template for="html" height="20">
                        <gs-button onclick="GS.pushQueryString('id=2341')">Record 1</gs-button>
                        <gs-button onclick="GS.pushQueryString('id=2342')">Record 2</gs-button>
                        <gs-form src="gsdoc.tpeople" where="id={{! qs.id }}" refresh-on-querystring-values="id">
                            <template>
                                <label for="first_name">First Name:</label>
                                <gs-text id="first_name" column="first_name"></gs-text>
                                
                                <label for="last_name">Last Name:</label>
                                <gs-text id="last_name" column="last_name"></gs-text>
                            </template>
                        </gs-form>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[refresh-on-querystring-change]</code>:</span>
                    <p>The "refresh-on-querystring-change" attribute refreshes the form element when anything changes in the query string.</p>
                </div>
                <gs-doc-example query-string="id=2341&unrelatedparameter=test">
                    <template for="html" height="20">
                        <gs-button onclick="GS.pushQueryString('refresh=' + window.refreshID++)">Update unrelated querystring column</gs-button>
                        <gs-form src="gsdoc.tpeople" where="id=2341" refresh-on-querystring-change>
                            <template>
                                <label for="first_name">First Name:</label>
                                <gs-text id="first_name" column="first_name"></gs-text>
                                
                                <label for="last_name">Last Name:</label>
                                <gs-text id="last_name" column="last_name"></gs-text>
                            </template>
                        </gs-form>
                    </template>
                    <template for="js" height="5">window.refreshID = 0;</template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[cols]</code>:</span>
                    <p>The "cols" attribute is for limiting the columns you get back from the database. Notice how the last_name column is not in the list and the last_name column is not filled in.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="20">
                        <gs-form src="gsdoc.tpeople" where="id=2341" cols="id,first_name,change_stamp">
                            <template>
                                <label for="text-id">ID:</label>
                                <gs-text id="text-id" column="id"></gs-text>
                                
                                <label for="text-first_name">First Name:</label>
                                <gs-text id="text-first_name" column="first_name"></gs-text>
                                
                                <label for="text-last_name">Last Name:</label>
                                <gs-text id="text-last_name" column="last_name"></gs-text>
                            </template>
                        </gs-form>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[save-while-typing]</code>:</span>
                    <p>the "size-while-typing" attribute causes the form to update after the user has stopped typing for a certain period of time. Doing this means the user does not have to leave the field or press return to save.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="15">
                        <gs-form src="gsdoc.tpeople" where="id=2341" save-while-typing>
                            <template>
                                <label for="first_name">First Name:</label>
                                <gs-text id="first_name" column="first_name"></gs-text>
                                
                                <label for="last_name">Last Name:</label>
                                <gs-text id="last_name" column="last_name"></gs-text>
                            </template>
                        </gs-form>
                    </template>
                </gs-doc-example>
                
                
                <div class="doc-example-description">
                    <span class="h3">"after_update" event and ".column()" method:</span>
                    <p>After an update, the "after_update" event gets triggered. To access a column inside this event and elsewhere, use the ".column()" method.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="15">
                        <gs-form id="form_name" src="gsdoc.tpeople" where="id=2341" save-while-typing>
                            <template>
                                <label for="first_name">First Name:</label>
                                <gs-text id="first_name" column="first_name"></gs-text>
                                
                                <label for="last_name">Last Name:</label>
                                <gs-text id="last_name" column="last_name"></gs-text>
                            </template>
                        </gs-form>
                    </template>
                    <template for="js" height="10">window.addEventListener('load', function (event) {
                        document.getElementById('form_name').addEventListener('after_update', function (event) {
                            alert(this.column('first_name'));
                        });
                    });</template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Javascript Methods:</span>
                    <p>These functions that can be run on individual <code>&lt;gs-form&gt;</code> elements:<br />
                    <i>FORM</i>.refresh() &lt;-- This method refreshes the <code>&lt;gs-form&gt;</code>.<br />
                    <i>FORM</i>.column(strColumn) &lt;-- This method get the current value of the column sent in "strColumn".<br />
                    <i>FORM</i>.addMessage(strMessageName) &lt;-- This method displays a small message at the top of the <code>&lt;gs-form&gt;</code>.<br />
                    <i>FORM</i>.removeMessage(strMessageName) &lt;-- This method remove the small message at the top of the <code>&lt;gs-form&gt;</code>.<br />
                </div>
                <gs-doc-example>
                    <template for="html" height="30">
                        <gs-button onclick="testrefresh()">Refresh Form</gs-button>
                        <gs-button onclick="testcolumn()">Get Column</gs-button>
                        <gs-button onclick="testaddMessage()">Add Message</gs-button>
                        <gs-button onclick="testremoveMessage()">Remove Message</gs-button>
                        <br />
                        <gs-form src="gsdoc.tpeople" where="id=2341" id="test-elem" cols="id,first_name,change_stamp">
                            <template>
                                <label for="text-id">ID:</label>
                                <gs-text id="text-id" column="id"></gs-text>
                                
                                <label for="text-first_name">First Name:</label>
                                <gs-text id="text-first_name" column="first_name"></gs-text>
                                
                                <label for="text-last_name">Last Name:</label>
                                <gs-text id="text-last_name" column="last_name"></gs-text>
                            </template>
                        </gs-form>
                    </template>
                    <template for="js" height="30">
                        function testrefresh() {
                            document.getElementById('test-elem').refresh();
                        }
                        function testcolumn() {
                            alert(document.getElementById('test-elem').column('first_name'));
                        }
                        function testaddMessage() {
                            document.getElementById('test-elem').addMessage('saving');
                        }
                        function testremoveMessage() {
                            document.getElementById('test-elem').removeMessage('saving');
                        }
                    </template>
                </gs-doc-example>
                
                
                
            </div>
        </gs-container>
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
    </body>
</html>